<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Hypergeometric pFq</title>
<link rel="stylesheet" href="../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Math Toolkit 4.1.0">
<link rel="up" href="../hypergeometric.html" title="Hypergeometric Functions">
<link rel="prev" href="hypergeometric_1f1.html" title="Hypergeometric 1F1">
<link rel="next" href="hypergeometric_refs.html" title="Hypergeometric References">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="hypergeometric_1f1.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../hypergeometric.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="hypergeometric_refs.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.hypergeometric.hypergeometric_pfq"></a><a class="link" href="hypergeometric_pfq.html" title="Hypergeometric pFq">Hypergeometric
      <sub>p</sub>F<sub>q</sub></a>
</h3></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">hypergeometric_pFq</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Real</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">);</span>

<span class="special">}}</span> <span class="comment">// namespaces</span>
</pre>
<h5>
<a name="math_toolkit.hypergeometric.hypergeometric_pfq.h0"></a>
        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_pfq.description"></a></span><a class="link" href="hypergeometric_pfq.html#math_toolkit.hypergeometric.hypergeometric_pfq.description">Description</a>
      </h5>
<p>
        The function <code class="computeroutput"><span class="identifier">hypergeometric_pFq</span></code>
        returns the result of:
      </p>
<div class="blockquote"><blockquote class="blockquote"><p>
          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_pfq_1.svg" width="409" height="53"></object></span>
        </p></blockquote></div>
<p>
        It is most naturally used via initializer lists as in:
      </p>
<pre class="programlisting"><span class="keyword">double</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">hypergeometric_pFq</span><span class="special">({</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">},</span> <span class="special">{</span><span class="number">5</span><span class="special">,</span><span class="number">6</span><span class="special">,</span><span class="number">7</span><span class="special">,</span><span class="number">8</span><span class="special">},</span> <span class="identifier">z</span><span class="special">);</span>  <span class="comment">// Calculate 3F4</span>
</pre>
<p>
        The optional <span class="emphasis"><em>p_abs_error</em></span> argument calculates an estimate
        of the absolute error in the result from the L1 norm of the sum, plus some
        other factors (see implementation below).
      </p>
<p>
        You should divide this value by the result to get an estimate of <span class="emphasis"><em>relative
        error</em></span>.
      </p>
<p>
        It should be noted that the error estimates are rather crude - the error
        can be significantly underestimated in some circumstances, and over-estimated
        in others.
      </p>
<p>
        The <code class="computeroutput"><span class="identifier">hypergeometric_pFq_precision</span></code>
        functions will calculate <code class="computeroutput"><span class="identifier">pFq</span></code>
        to a specified number of decimal places, and if <code class="computeroutput"><span class="identifier">timeout</span></code>
        is reached then they raise an <a class="link" href="../error_handling.html#math_toolkit.error_handling.evaluation_error">evaluation_error</a>.
        Note that while these functions are defined as templates, they require type
        <code class="computeroutput"><span class="identifier">Real</span></code> to be a <span class="bold"><strong>variable-precision</strong></span>
        floating-point type: in practice the only type currently supported (as of
        July 2019) is <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">mpfr_float</span></code>. Typical usage would be:
      </p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">mpfr_float</span> <span class="identifier">mp_type</span><span class="special">;</span>
<span class="comment">//</span>
<span class="comment">// Calculate 2F2 to 20 decimal places using a 10 second timeout:</span>
<span class="comment">//</span>
<span class="identifier">mp_type</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span>
  <span class="special">{</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">a1</span><span class="special">),</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">a2</span><span class="special">)</span> <span class="special">},</span> <span class="special">{</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">b1</span><span class="special">),</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">b2</span><span class="special">)</span> <span class="special">},</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">z</span><span class="special">),</span> <span class="number">20</span><span class="special">,</span> <span class="number">10.0</span>
  <span class="special">);</span>
<span class="comment">//</span>
<span class="comment">// Convert the result back to a double:</span>
<span class="comment">//</span>
<span class="keyword">double</span> <span class="identifier">d_result</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(</span><span class="identifier">result</span><span class="special">);</span>
</pre>
<h5>
<a name="math_toolkit.hypergeometric.hypergeometric_pfq.h1"></a>
        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_pfq.implementation"></a></span><a class="link" href="hypergeometric_pfq.html#math_toolkit.hypergeometric.hypergeometric_pfq.implementation">Implementation</a>
      </h5>
<p>
        This function is implemented by direct summation of the series; summation
        normally starts with the zeroth term, but will skip forward and sum outward
        (ie in both forward and backward directions) from some term <span class="emphasis"><em>N</em></span>
        when required. This is particularly important when some of the <span class="emphasis"><em>b</em></span>
        arguments are negative, as in this situation the sum undergoes "false-convergence",
        and then diverges again as each b<sub>j</sub> passes the origin. Consequently, were you
        to plot the magnitude of the terms in the sum, you would see them pass through
        a series of minima and maxima before finally converging to zero at infinity.
        For some values of <span class="emphasis"><em>p</em></span> and <span class="emphasis"><em>q</em></span> we can
        compute where the maxima occur, and therefore sum only the terms that will
        have an impact on the result. For other <span class="emphasis"><em>p</em></span> and <span class="emphasis"><em>q</em></span>
        values, predicting the exact locations of the maxima is not so easy, and
        we simply restart summation at the point where each b<sub>j</sub> passes the origin:
        this will eventually reach all the significant terms of the sum, but the
        key word may well be "eventually".
      </p>
<p>
        The error term <span class="emphasis"><em>p_abs_error</em></span> is normally simply the sum
        of the absolute values of each term multiplied by machine epsilon for type
        <code class="computeroutput"><span class="identifier">Real</span></code>. However, if it was
        necessary for the summation to skip forward, then <span class="emphasis"><em>p_abs_error</em></span>
        is adjusted to account for the error inherent in calculating the N'th term
        via logarithms.
      </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="hypergeometric_1f1.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../hypergeometric.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="hypergeometric_refs.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
